Summary

This PR implements Calendar Versioning (CalVer) with beta release support, matching the versioning scheme used in CeraUI. This provides human-readable version numbers and proper release channels for stable and beta releases.

Changes

🔄 Updated Workflows

.github/workflows/release.yml

• ✅ Add workflow dispatch inputs:
  • release_type: Choose between stable or beta
  • release_notes: Optional release description
  • force_version: Override auto-detected version if needed
• ✅ Implement CalVer calculation with beta support
  • Stable: YYYY.M.patch (e.g., v2026.1.0, v2026.1.1)
  • Beta: YYYY.M.patch-beta.N (e.g., v2026.1.2-beta.1)
• ✅ Auto-increment versions based on existing git tags
• ✅ Mark beta releases as pre-releases on GitHub
• ✅ Generate changelog from commit history
• ✅ Enhanced release notes formatting

.github/workflows/publish-deb.yml

• ✅ Use CalVer for Debian package versions
• ✅ Support stable and beta package builds
• ✅ Update package metadata (changed from irl-belacoder to ceracoder)
• ✅ Manual trigger with release type selection

📚 Documentation

New: docs/versioning.md

Comprehensive documentation covering:

• Version format explanation with examples
• Version calculation rules for stable and beta releases
• Step-by-step release creation guide via GitHub Actions
• Workflow details and inputs
• Best practices for when to use stable vs beta
• Troubleshooting common issues
• Migration notes from commit-hash versioning

Updated: README.md

• Added link to versioning documentation

Version Format

Example Version Progression

January 2026:
  v2026.1.0           ← First stable release
  v2026.1.1           ← Second stable release
  v2026.1.2-beta.1    ← First beta (next patch)
  v2026.1.2-beta.2    ← Second beta
  v2026.1.2           ← Stable release

February 2026 (new month, patch resets):
  v2026.2.0           ← First stable of new month
  v2026.2.1-beta.1    ← First beta

How to Use

Creating a Release

1. Go to Actions → Build and Release Ceracoder
2. Click Run workflow
3. Select:
   • Release type: stable or beta
   • Release notes: Optional description of changes
4. Click Run workflow

The workflow automatically:

• Calculates the next version
• Builds for x86_64 and ARM64
• Creates GitHub release with binaries
• Tags appropriately (with pre-release flag for betas)

Benefits

✅ Human-readable versions - Date-based versions instead of commit hashes
✅ Beta testing workflow - Test features before stable release
✅ Consistency with CeraUI - Same versioning scheme across projects
✅ Automatic versioning - No manual version bumping
✅ Month-based cycles - Natural release cadence
✅ Pre-release tagging - Beta releases clearly marked on GitHub

Testing

The versioning logic has been tested and verified to match CeraUI's implementation. The workflow will calculate versions based on existing tags in the repository.

Migration

This change is backward compatible. Existing installations with commit-hash versions will continue to work. New releases will use the CalVer format starting from the next release.

Closes: N/A (New feature)
Related: Aligns with CeraUI versioning scheme